tools/toolbox: Document new sysext tooling

Add a small section to outline how to combine `meson-build.sh --sysext` and
`toolbox-sysext-install.sh` to install a system extension from our toolboxes.

Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/3498>

diff --git a/tools/toolbox/README.md b/tools/toolbox/README.md
index 3b695db2da8736a855fc30aff9e13d5519ead731..e4bbb816e3bfbf5d05a7558790f24af8372afe52 100644 (file)
--- a/tools/toolbox/README.md
+++ b/tools/toolbox/README.md
@@ -57,9 +57,39 @@ simulating multiple monitors or a greeter session.
 
 Run the script with `--help` to see all available options.
 
+## toolbox-sysext-install.sh
+
+Extract a prepared system extension directory from the toolbox and
+install it as [systemd-sysext] extension on the host.
+
+The `meson-build.sh` script has a `--sysext` option to easily add
+projects to the extension directory in the toolbox:
+
+```sh
+  $ cd path/to/mutter; meson-build.sh --sysext
+  $ cd path/to/gnome-shell; meson-build.sh --sysext
+  $ toolbox-sysext-install.sh
+```
+
+System extensions require that the host operating system matches
+the extension. For toolboxes created with the `create-toolbox.sh`
+script this means the most recent Fedora release.
+
+### Important note
+
+gnome-shell is tightly coupled with mutter, so an extension that
+only contains gnome-shell is very likely to fail. The `update-mutter`
+command inside the toolbox already takes care of this, but when
+building mutter manually, it is the responsibility of the caller
+to ensure that the system extension contains a recent-enough
+mutter build.
+
+Run the script with `--help` to see available options.
+
 [toolbox]: https://containertoolbx.org/
 [mutter]: https://gitlab.gnome.org/GNOME/mutter
 [builder]: https://apps.gnome.org/Builder/
 [meson]: https://mesonbuild.com
 [handbook]: https://handbook.gnome.org/
 [troubleshooting]: https://handbook.gnome.org/development/toolbx.html#when-things-go-wrong
+[systemd-sysext]: https://www.freedesktop.org/software/systemd/man/latest/systemd-sysext.html